README file for JADE, Version $Name: JADE-2_4 $

INTRODUCTION
============
This package contains a Java framework to build agent-based systems
according to FIPA standard specifications.

LICENSE
=======
see file License.

FEEDBACK
=======
As you know already, this is still an on-going project. 
We are still working on the framework and new versions will be distributed 
as soon as available.
Your feedback as users is very important to us. Please, if you have new 
requirements that you would like to see implemented or if you have examples 
of usage or if you discover some bugs, send us information.
Check the website http://jade.cselt.it/
for how to report bugs and send suggestions.  

SYSTEM REQUIREMENTS
===================
To build the framework a complete Java programming environment is
needed. At least a Java Development Kit version 1.2 is required. 


KNOWN BUGS
==========
  1) On Solaris 7 with Jdk 1.2, a message "Resource temporarily
     unavailable" appears during platform shutdown, but then the
     process completes without any problems.

  2) The second argument of the ResultPredicate is limited to be a SET.


CONTACT
=======
Fabio Bellifemine - CSELT Centro Studi e Laboratori Telecomunicazioni S.p.A.
e-mail: bellifemine@cselt.it

Tiziana Trucco - CSELT Centro Studi e Laboratori Telecomunicazioni S.p.A.
e-mail tiziana.trucco@cselt.it


INSTALLATION AND TEST
==============================
You can download JADE in source form and recompile it yourself, 
or get the pre-compiled binaries (actually they are JAR files). 
The following is an excerpt from the programmer's guide.

5.1 Software requirements
=========================
The only software requirement to execute the system is the Java Run Time 
Environment version 1.2
Further to the Java Compiler version 1.2, to build the system, the JavaCC 
parser generator (version 0.8pre or version 1.1; available from 
http://www.metamata.com), and the IDL to Java translator idltojava 
(available from the Sun Developer Connection) are also needed. However, 
pre-built IDL stubs and Java parser classes are included with the JADE 
source distribution such that the Java compiler is sufficient to build 
the full system.

5.2 Getting the software
========================
All the software is distributed under the LGPL license limitations. 
It can be downloaded from the JADE web site 
http://jade.cselt.it/ Five compressed files are available:
1. the source code of JADE
2. the source code of the examples
3. the documentation, including the javadoc of the JADE API and 
this programmer's guide
4. the binary of JADE, i.e. the jar files with all the Java classes
5. a full distribution with all the previous files


5.3 Running JADE from the binary distribution
=============================================
Having uncompressed the archive file, a directory tree is generated whose 
root is jade and with a lib subdirectory. This subdirectory contains some 
JAR files that have to be added to the CLASSPATH environment variable.
Having set the classpath, the following command can be used to launch the 
main container of the platform. The main container is composed of the DF 
agent, the AMS agent, an RMI registry (that is used by JADE for 
intra-platform communication), and the ACC.
        java jade.Boot [options] [Agent list]
Additional agent containers can be then launched on the same host, or on 
remote hosts, that connect themselves with the main container of the Agent 
Platform, resulting in a distributed system that seems a single Agent 
Platform from the outside.
An Agent Container can be started using the command:
        java jade.Boot -container [options] [Agent list]

An alternative way of launching JADE is the following command:
        java -jar lib\jade.jar -nomtp [options] [Agent list]

5.3.1 Options available from the command line
=============================================
-h this option prints on the standard output some help on the available 
options
-container this option launches a container that try to connect with a main 
container
-host <hostname> should be used to specify the host where the main container 
has been launched; the default is the local host.
-port <portnumber> this option allows to specify the port number where the 
RMI registry should be created (for the main-container) / located 
(for the ordinary containers)
-conf this option displays a graphical interface that allows to load/save 
the JADE configuration from a file
-conf <fileName> launches JADE with the options specified in the fileName.
-gui this option launches a Remote Monitoring Agent, a graphical interface 
that allows to monitor the agent platform (see section 6).
-version -prints on the standard output versioning information of JADE.
-name <symbolicname> specifies the symbolic name to be used as the 
platform name; this option should be specified only for the main container; the
 default is to generate this from the values of the main container's hostname 
and portnumber


5.3.2 Launching agents from the command line
============================================
A list of agents can be launched directly from the command line. As described
above, the [Agent list] part of the command is a sequence of strings separated
by a space.
Each string is broken in two parts separated by a colon ':' character. The 
substring before the colon is taken as the agent name, whereas the substring 
after the colon is the name of the Java class implementing the agent. This 
class will be dynamically loaded by the Agent Container.
For example, a string Peter:myAgent means "create a new agent named Peter 
whose implementation is an object of class myAgent". The name of the class 
must be fully qualified, (e.g. Peter:myPackage.myAgent) and will be searched 
for according to CLASSPATH definition.

5.3.3 Example
=============
First of all set the CLASSPATH to include the JAR files in the lib 
subdirectory and the current directory. For instance, for Windows 9x/NT use 
the following command:
set CLASSPATH=%CLASSPATH%;.;c:\jade\lib\jade.jar;
                c:\jade\lib\jadeTools.jar; c:\jade\lib\Base64.jar;
		c:\jade\lib\iiop.jar
Execute the following command to start the main-container of the platform. 
Let's suppose that the hostname of this machine is "kim.cselt.it"
prompt> java jade.Boot -gui 
Execute the following command to start an agent container on another machine,
by telling it to join the AgentPlatform, called "facts" running on the host 
"kim.cselt.it", and start one agent (you must download and compile the 
examples agents to do that): 
prompt> java jade.Boot -host kim.cselt.it -container
          sender1:examples.receivers.AgentSender 
where "sender1" is the name of the agent,  
while examples.receivers.AgentSender is the code that implements the agent.
Execute the following command on a third machine to start another agent 
container telling it to join the Agent Platform, called "facts" running on 
the host "kim.cselt.it", and then start two agents. 
prompt> java jade.Boot -host kim.cselt.it -container 
          receiver2:examples.receivers.AgentReceiver 
          sender2:examples.receivers.AgentSender
where the agent named sender2 is implemented by the class 
examples.receivers.AgentSender, while the agent named receiver2 is 
implemented by the class examples.receivers.AgentReceiver.

5.4 Building JADE from the source distribution
==============================================
If you downloaded JADE in source form and want to compile it, you basically 
have two methods: either you use the provided makefiles (for GNU make), or 
you run the Win32 .BAT files that you find in the root directory of the 
package. Of course, using makefiles yields more flexibility because they 
just build what is needed; JADE makefiles have been tested under Sun 
Solaris 7 with JDK 1.2.0 and under Linux under JDK 1.2.2 RC4. The batch 
files have been tested under Windows NT 4.0 and under Windows 95, both with 
JDK 1.2.2.

5.4.1 Building the JADE framework
=================================
If you use the makefiles, just type
make all
in the root directory; if you use the batch files, type
makejade
in the root directory. Beware that the batch file will not be able to check 
whether IDL stubs and parser classes already exist, so either you have 
idltojava and JavaCC installed, or you comment out them in the batch file.
You will end up with all JADE classes in a classes subdirectory. You can add 
that directory to your CLASSPATH and make sure that everything is OK by 
running JADE, as described in the previous section.

5.4.2 Building JADE libraries
============================
With makefiles, type
make lib
With batch files, type
makelib
This will remove the content of the classes directory and will create some 
JAR files in the lib directory. These JAR files are just the same you get 
from the binary distribution. See section 5.3 for a description on how to 
run JADE when you have built the JAR files. Beware that, both with makefiles 
and batches, you must first build the classes and then the libraries, 
otherwise you will end up with empty JAR files.
NOTE: jade/lib/Base64.jar is only needed if you want to use the support for JADE 
      serialization and trasmitting sequences of bytes within an ACLMessage. In all
      other cases, it is not necessary adding it to CLASSPATH .

5.4.3 Building JADE HTML documentation
======================================
With makefiles, type
make doc
With batch files, type
makedoc
You will end up with Javadoc generated HTML pages, integrated within the 
overall documentation. Beware that the Programmer's Guide is a PDF file that 
cannot be generated at your site, but you must download it (it is, of course,
in the JADE documentation distribution).

5.4.4 Building JADE examples and demo application
=================================================
If you downloaded the examples/demo archive and have unpacked it within the 
same source tree, you will have to set your CLASSPATH to contain either the 
classes directory or the JAR files in the lib directory, depending on your 
JADE distribution, and then type:
make examples
with makefiles, or
makeexamples
with batch files.
In order to compile the Jess-based example, it is necessary to have the JESS 
system and to set the CLASSPATH to include it. The example can be compiled 
by typing:
make jessexample
with makefiles, or
makejessexample
with batch files.

5.4.5 Cleaning up the source tree
=================================
If you type
make clean
with makefiles, or if you type
clean
with batch files, you will remove all generated files (classes, HTML pages, 
JAR files, etc.) from the source tree. If you use makefiles, you will find 
some other make targets you can use. Feel free to try them, especially if 
you are modifying JADE source code, but be aware that these other make 
targets are for internal use only, so they have not been documented.

5.5 IIOP support and inter-platform messaging
=============================================
JADE supports FIPA compliant IIIOP communication for inter-platform agent 
communication. This mechanism is used both to communicate with another JADE 
platform and with a non-JADE platform. JADE achieves complete transparency 
in message passing even when multiple agent platforms are involved, so agent 
developers need not worry about IIOP: JADE selects local Java events, RMI or 
CORBA/IIOP automatically on behalf of the application.
The only issue application developers and platform administrators must be 
aware-of is agent naming. An agent identifier, in fact, must include a set 
of URL representing the addresses where it can be contacted.
Every JADE agent inherits the addresses of its platform and its AID 
(including the addresses) is fully generated automatically by JADE when 
messages are sent externally to the platform. 
Because most of the CORBA ORB implementations (including the one used by 
JADE) do not yet allow to choose meaningful words as object keys, JADE 
resorts to the alternate naming scheme, adopted also by FIPA 98 version 2.0, 
using OMG standard stringified IOR as agent addresses. A valid agent address 
can be both an URL like iiop://fipa.org:50/acc and an IOR as 
IOR:000000000000001649444c644f4)
The IOR-based representation and the URL-based one are exactly equivalent, 
the URL being far more readable for humans than the IOR. JADE generates 
IOR-based addresses but can also deal with URL-based ones as long as the URL 
contains only printable characters (i.e. has been created by an ORB allowing 
explicit object key assignment) that can be parsed by a FIPA-compliant parser.
When starting up, JADE platform prints its IOR both on the standard output 
and in a ASCII file named JADE.IOR, located in the current directory; the 
URL for the platform (containing a binary string in the file part) is also 
written to the file JADE.URL in the current directory. Every agent address 
automatically includes this platform IOR that should be distributed to remote 
platforms in order to allow remote agents to send messages to your JADE 
agents. The distribution mechanism is not specified by FIPA and is 
application dependent. 
